affinityScoresByConfig API

Description

The affinityScoresByConfig API returns affinity scores for a shopper based on the specified affinity configuration. The API evaluates the shopper’s behavior and generates scores for configured dimensions such as brands, categories, or product attributes. These scores help determine the shopper’s level of interest in each dimension.

https://recs.richrelevance.com/rrserver/api/rrPlatform/affinityScoresByConfig

Parameters

Note: All parameters are case sensitive.

IMPORTANT: Only call parameters that you need. ADA operates off a set of APIs that support many applications and clients concurrently. ADA may update and enhance these APIs at any time.

Name	Required or Optional	Description
affinityConfigName	Optional	The affinity configuration to use. If omitted, the system uses the default configuration.
apiClientKey	Required	A unique key specific to each API implementation. It identifies the specific application or client for reporting, permissions, and merchandising. This is provided by ADA. Example: apiClientKey=b0126f995ac848159d
apiKey	Required	A unique key that identifies the site. Each ADA client has a unique API key to separate data and traffic from other clients. This is provided by ADA. Example: apiKey=4faeaf752ee40a0f
rcs	Optional	ADA Cookie String. This is the encrypted ADA cookie for the user associated with the API request. It should be passed exactly as it was received in a prior API response. Clients should ensure to preserve the 'rcs' value just as it was served. The 'rcs' parameter is always alphanumeric and case-sensitive, with the token value including a mix of uppercase letters, lowercase letters, and numbers. Note: The 'rcs' parameter allows merchants to effectively provide the ADA platform access to a user's ADA browser cookie by acting as a cookie proxy (or cookie pass-through). This process involves the merchant reading and writing a user's ADA browser cookie and passing it to and from ADA via the server-side API.
sessionId	Optional	Identifies a single visit by a shopper. Sessions are used by behavioral models (to scope user behavior in a shopping session) and reporting metrics. Example: sessionId=93484
userId	Optional	User ID. A unique string to identify each shopper (user). All shopper behavior is stored using this key. It is case-sensitive, and should be the same user ID sent to ADA in other applications. Example: userId=0982347 If no userID is given, recommendations are based on view and purchase history (via the recentlyViewed and recentlyPurchased parameters or cookies) as well as unpersonalized strategies such as CategoryBestSellers.

Sample Request

Copy

http://recs.richrelevance.com/rrserver/api/rrPlatform/affinityScoresByConfig?

Sample Response

{
"brandScores": {
"viewScores": [
{ "affinity": "Aquazzura", "score": 1.9 }
],
"purchaseScores": [],
"cartScores": [
{ "affinity": "Marni", "score": 2.85 },
{ "affinity": "Aquazzura", "score": 2.85 }
],
"wishlistScores": [],
"categoryViewScores": [],
"combinedScores": [
{ "affinity": "Marni", "score": 2.85 },
{ "affinity": "Aquazzura", "score": 4.75 }
]
},

"categoryScores": {
"viewScores": [
{ "affinity": { "externalId": "77", "name": "Sandals" }, "score": 1.82 },
{ "affinity": { "externalId": "74", "name": "Shoes" }, "score": 1.82 },
{ "affinity": { "externalId": "10", "name": "Womens" }, "score": 1.82 }
],
"purchaseScores": [],
"cartScores": [
{ "affinity": { "externalId": "76", "name": "Pumps" }, "score": 2.73 },
{ "affinity": { "externalId": "65", "name": "Jewellery" }, "score": 2.73 },
{ "affinity": { "externalId": "74", "name": "Shoes" }, "score": 2.73 },
{ "affinity": { "externalId": "10", "name": "Womens" }, "score": 5.46 },
{ "affinity": { "externalId": "67", "name": "Necklaces" }, "score": 2.73 }
],
"wishlistScores": [],
"categoryViewScores": [],
"combinedScores": [
{ "affinity": { "externalId": "76", "name": "Pumps" }, "score": 2.73 },
{ "affinity": { "externalId": "77", "name": "Sandals" }, "score": 1.82 },
{ "affinity": { "externalId": "65", "name": "Jewellery" }, "score": 2.73 },
{ "affinity": { "externalId": "74", "name": "Shoes" }, "score": 4.55 },
{ "affinity": { "externalId": "10", "name": "Womens" }, "score": 7.28 },
{ "affinity": { "externalId": "67", "name": "Necklaces" }, "score": 2.73 }
]
},

"attributeScores": {
"viewScores": [
{
"affinity": { "attributeName": "ColorCode", "attributeValue": "black~black" },
"score": 0.95
},
{
"affinity": { "attributeName": "size", "attributeValue": "7~8~9~10~11" },
"score": 0.28
},
{
"affinity": { "attributeName": "size", "attributeValue": "10~11~12~13~14" },
"score": 0.28
},
{
"affinity": { "attributeName": "ColorCode", "attributeValue": "brown~cognac" },
"score": 0.95
}
],
"purchaseScores": [],
"cartScores": [
{
"affinity": { "attributeName": "size", "attributeValue": "5~6~7~8~9" },
"score": 0.84
},
{
"affinity": { "attributeName": "ColorCode", "attributeValue": "metallic~blacksilver" },
"score": 2.85
},
{
"affinity": { "attributeName": "size", "attributeValue": "10~11~12~13~14" },
"score": 0.84
},
{
"affinity": { "attributeName": "ColorCode", "attributeValue": "metallic~green~00w01lilywhite" },
"score": 2.85
}
],
"wishlistScores": [],
"categoryViewScores": [],
"combinedScores": [
{
"affinity": { "attributeName": "ColorCode", "attributeValue": "black~black" },
"score": 0.95
},
{
"affinity": { "attributeName": "size", "attributeValue": "5~6~7~8~9" },
"score": 0.84
},
{
"affinity": { "attributeName": "size", "attributeValue": "7~8~9~10~11" },
"score": 0.28
},
{
"affinity": { "attributeName": "ColorCode", "attributeValue": "metallic~blacksilver" },
"score": 2.85
},
{
"affinity": { "attributeName": "size", "attributeValue": "10~11~12~13~14" },
"score": 1.12
},
{
"affinity": { "attributeName": "ColorCode", "attributeValue": "brown~cognac" },
"score": 0.95
},
{
"affinity": { "attributeName": "ColorCode", "attributeValue": "metallic~green~00w01lilywhite" },
"score": 2.85
}
]
}
}

Field Description

Field	Description
brandScores	Contains affinity scores related to brands. Includes view, purchase, cart, wishlist, category-view, and combined scores.
categoryScores	Contains affinity scores related to categories. Includes view, purchase, cart, wishlist, category-view, and combined scores.
attributeScores	Contains affinity scores related to product attributes such as color, size, or other configured attribute types.
viewScores	Affinity scores calculated from products that the shopper viewed.
purchaseScores	Affinity scores calculated from products purchased by the shopper.
cartScores	Affinity scores calculated from products added to the cart.
wishlistScores	Affinity scores calculated from products added to the wishlist or favorites.
categoryViewScores	Category-level affinity scores based on viewing behavior.
combinedScores	Aggregated affinity values across all behaviors. Represents the highest-confidence affinity score per dimension.
affinity.externalId	The external ID of the category, as defined in the merchant catalog.
affinity.name	The category name.
attributeName	The name of the attribute (for example, ColorCode, size).
attributeValue	The attribute value. Multiple values are separated by the ~ delimiter.
score	The affinity score assigned to the brand, category, or attribute. Higher scores indicate stronger preference.

Throttling of API Requests

Affinity Scores API requests will process up to a maximum of 1000 requests per minute. Ensure that your application throttles requests accordingly.